Copyright (c) 1999 Massachusetts Institute of Technology

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see https://gnu.org/licenses or write
to:
  Free Software Foundation, Inc.
  51 Franklin Street, Fifth Floor
  Boston, MA 02110-1301
  USA
------------------------------

ITS INTERRUPTS:

This file attempts to maintain up-to-date documentation on
ITS interrupts.  Those wonderful
souls who update the information in any way (additions,
deletions, corrections) should describe their
modifications in a brief note to INFO-ITS@AI so
that interested parties can correct their copies or
conceptions without needing to print or read the
entire file again.  For example:

	:QMAIL INFO-ITS@AI I added more details to the %PIJST interrupt ^C

If you want to be put on the INFO-ITS mailing list,
just say so in a message to it.
-------------------------------------------------

<Most of ITS INTRUP is not here...>

FIRST		The Interrupt Bits in the First Interrupt Word.

The interrupt classes are:
  [1] stops job and interrupts superior (fatal intr)
  [2] stops job and interrupts superior unless enabled and undeferred
  [3] does nothing unless enabled;  waits if deferred.

Bits in the left half have two names: %PI... as a bit in the word,
and %PJ... shifted down by 18. bits.

The following interrupts abort the instruction, and leave the PC pointing
before the instruction if %OPOPC is 1 (as is winning), or after it if
%OPOPC is 0:  %PIMPV, %PIOOB, %PIIOC, %PIILO, %PITTY, %PIWRO, %PIFET, %PITRP.

"(S)" indicates a synchronous interrupt;  "(A)", an asynchronous one.
An interrupt is synchronous if its occurrence is always directly related
to the instruction that is being executed when it is signaled.

SECOND		The Interrupt Bits in the Second Interrupt Word.

The right half of the second word (.IFPIR) is used for I/O channel
interrupts that signal the arrival of or need for data.
They should not be confused with I/O channel error interrupts
or IOCERRors.  Each channel has its own bit: 1.1 is for channel
0;  1.2, for channel 1; ... 2.7, for channel 17 .
They are all class 3, and their significance depends on the device
open on the channel.

The left half of the second word (.IFPIR) is used for
"inferior got a fatal interrupt" interrupts.  Each of a job's
inferiors is assigned its own interrupt bit from among the
bottom 8 bits of the left half.  When an inferior job is created,
its interrupt bit should be read and remembered by reading the
.INTB variable with a .USET.  Every time that inferior gets a fatal
interrupt, it will be stopped and the superior will receive an
interrupt on that inferior's bit in .IFPIR.  The inferior may
be restarted by zeroing its .USTP variable, but if the fatal
interrupts remain and are still fatal the inferior will simply
stop and interrupt the superior again.  "Inferior got a fatal
interrupt" interrupts are all class 3.

The reason that inferiors interrupt through a special set of bits
instead of using I/O channel interrupts is that it makes it possible
to receive interrupts from all one's inferiors without having them
all open on I/O channels at all times.  DDT normally keeps only
its current job open, and when it receives an interrupt from some
other job it opens that job temporarily.

STACK		The format of the new-style interrupt stack

		-----------------------------------
		|     1st word interrupt bits	  |
		-----------------------------------
		|     2nd word interrupt bits	  |
		-----------------------------------
		|	    Saved .DF1		  |
		-----------------------------------
		|	    Saved .DF2		  |
		-----------------------------------
		|      Saved program counter	  |
		-----------------------------------
		|	       . . .		  |
		|   Saved accumulators, if any	  |
		|	       . . .		  |
		-----------------------------------
		|    Saved .JPC, if requested	  |
		-----------------------------------
		|   Saved .SUUOH, if requested	  |
		-----------------------------------
	Top ->	|    Saved LSPCL, if requested	  |
		-----------------------------------

%PICLI		CLI interrupt				[3] (A)

		Some job opened the CLI device with filenames equal
		to the uname and jname of this job.

%PIPDL		PDL overflow				[3] (S)

%PILTP		340 or E&S light pen hit		[3] (A)

%PIMAR		MAR hit.				[2] (S)

		The MAR is a hardware feature that allows
		references to a specific memory location to
		be trapped.  This is the interrupt that happens
		when such a reference is detected.  The guilty
		instuction is usually not aborted;  if it is, the
		PC is SOS'ed regardless of the setting of %OPOPC.
		See the .MARA and .MARPC variables.

%PIMPV		MPV (memory protect violation)		[2] (S)

		The job referenced a non-existent memory location.
		The address of that location (roundd down to
		a page boundary on KA-10's) may be found in .MPVA.
		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.

%PICLK		Slow (1/2 sec) clock			[3] (A)

%PI1PR		Single-instruction proceed		[1] (S)

		If a job is started with the one-proceed flag
		(%PC1PR on KA-10's) set, after one instruction
		is completed a %PI1PR interrupt will occur.
		DDT's ^N command uses this feature.

%PIBRK		.BREAK instruction executed.		[1] (S)

		.BREAK is used for DDT breakpoints, and for explicit
		program requests to DDT.

%PIOOB		Address out of bounds			[2] (S)

		This is an obscure condition that used to
		happen on USR device IOT's, when an attempt
		was made to refer to a nonexistent location in the
		other job.  Now this always causes an MPV.
		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.

%PIIOC		IOCERR (I/O channel error)		[2] (S)

		This indicates the failure of an I/O system
		call.  The channel that was being operated on is
		in .BCHN, and its .IOS word should contain, in
		bits 4.5 - 4.1, an error code.
		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.

%PIVAL		.VALUE instruction executed		[1] (S)

%PIDWN		System-going-down status change		[3] (A)

		If the system changes its mind about whether
		or when it is scheduled to go down, this interrupt
		is signaled.

%PIILO		ILOPR, ILUUO (illegal operation)	[2] (S)

		This can be caused by a returnable uuo when the
		program's 41 doesn't seem suitable for handling one
		(see ITS UUOS).  It can also be used to report
		the failure of certain more archaic system calls.
		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.

%PIDIS		Display memory protect			[2] (A)

		The 340 or E&S display got an MPV.
		This is now obsolete since the 340 and E&S
		no longer work.

%PIARO		Arithmetic overflow			[3] (S)

		The PDP-10's built-in arithmetic overflow
		condition was detected by the hardware.
		In fact, overflow occurs so often
		that enabling this interrupt causes the
		machine to slow down considerably,
		and it should be avoided.

%PIB42		BADPI (Bad location 42)			[1] (S)

		If in attempting to interrupt a job it turns out
		to be necessary to refer to nonexistent memory
		or write in read-only memory, this interrupt
		is signaled, instead of MPV or WIRO.
		This is so that the program will return to DDT
		instead of mysteriously looping.

%PIC.Z		^Z or CALL typed on terminal		[1] (A)

%PITYI		TTY input (obsolete)			[3] (A)

%PIRLT		Real-time timer went off		[3] (A)

		These interrupts are controlled by the .REALT
		uuo.  See ITS UUOS.

%PIRUN		Run-time timer went off			[3] (A)

		This interrupt is requested (in advance)
		by setting .RTMR.

%PINXI		Non-existent IO register		[2] (S)

		A Job in User IOT mode referenced a non-existent IO
		register on the KS10 Unibus.  The PC is left pointing
		before the guilty instruction.  The address of the
		non-existant register may be found in .MPVA.

%PIJST		Job Status display request.		[3] (A)

		The sequence ^_J was typed on the
		console owned by this process or some inferior.

%PIDCL		Deferred call.				[1] (S)

		An attempt was made to read TTY input
		and the next character was a deferred-call
		character (^_D or Control-CALL).
		This deferred-call character is never seen
		by the program; it just causes the interrupt.
		It differs from ordinary CALL or ^Z
		in that it takes effect when the program
		gets around to reading it, not immediately.

%PIATY		TTY returned.				[3] (A)

		This interrupt happens when the TTY is
		returned by the superior, after having
		been taken away.  TECO uses this to know
		that it must redisplay the entire screen.

%PITTY		Don't have TTY				[2] (S)

		This results from an attempt to use the job's
		console tty when the job does not own it, if
		%TBINT is 1 and %TBWAT is 0.  See ITS TTY.
		The guilty instruction is aborted, and the PC is
		left set according to %OPOPC.

%PIPAR		Memory parity error			[2] (A)

		Programs are not intended to try to recover
		from parity errors, on the assumption that they
		are probably permanently screwed up.
		This interrupt is asynchronous because it can
		be caused by a parity error in another job
		which destroys data in a page shared with this job.

%PIFOV		ARFOV (Floating overflow)		[3] (S)

		This is a non-aborting PDP-10 hardware condition.

%PIWRO		WIRO (Write in read-only page)		[2] (S)

		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.  The address of read
		only location (rounded down to a page boundary on
		KA-10's) may be found in .MPVA.

%PIFET		Fetched insn from impure page		[2] (S)

		On KA-10's, if bit %PCPUR of the PC flags is 1,
		fetching an instruction from an impure page
		will cause this interrupt.  This is supposed to
		facilitate catching jumps to randomness.
		The guilty instruction is aborted, and the PC is
		left set according to %OPOPC.

%PITRP		SYSUUO (System uuo in trap mode)	[2] (S)

		A job whose .UTRAP variable was nonzero either
		attempted to execute an instruction that trapped
		to the system, or was about to be interrupted.
		This feature is intended to be used by the superior
		to provide a non-ITS environment for the inferior.
		For that purpose, this interrupt should not be
		enabled for the inferior, so that it will be fatal.
		The guilty instruction was aborted, and the PC was
		left set according to %OPOPC.

%PIDBG		System being debugged state change	[3] (A)

		When the system enters or leaves "debugging mode",
		this interrupt is signaled.

%PILOS		Lossage signaled.			[2] (S)
		
		A .LOSE UUO or a LOSE system call was executed.
